gdkwindow: Add some extra documentation to gdk_cairo_create

Mention the need to wrap the function inside
gdk_window_begin_paint_region and gdk_window_end_paint.

diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 36d01e4ccecda53a1cf1ffbe9ef712eddc78056e..fcb4cdbb2c58e09b004242b0bf0c58f5757f6979 100644 (file)
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -3030,6 +3030,11 @@ _gdk_window_ref_cairo_surface (GdkWindow *window)
  * Note that calling cairo_reset_clip() on the resulting #cairo_t will
  * produce undefined results, so avoid it at all costs.
  *
+ * As of GTK+ 3.14, you need to wrap calls to this function with
+ * gdk_window_begin_paint_region() / gdk_window_begin_paint_rect() and
+ * gdk_window_end_paint(). Calling it outside of a "paint" will
+ * result in a warning printed and a dummy surface being returned.
+ *
  * Returns: A newly created Cairo context. Free with
  *  cairo_destroy() when you are done drawing.
  *